Geavanceerde query parameters
De dynamische API ondersteunt verschillende query parameters om je API-aanroepen te verfijnen en filteren. Deze geavanceerde functies maken het mogelijk om specifieke data op te halen zonder uitgebreide client-side filtering te implementeren.
Wat is een query parameter?
Een query parameter is een stuk informatie die je kan toevoegen aan het einde van een URL om je request specifieker te maken. Bijvoorbeeld:
/api/products?fields=name,price
Alles achter de ? wordt gezien als een query parameter. In het bovenstaande voorbeeld proberen we alleen de naam en
prijs van elk product op te halen.
Meerdere query parameters combineren
Je kunt meerdere query parameters in één request combineren door ze te scheiden met het & teken.
/api/products?fields=name,price&limit=10
In het bovenstaande voorbeeld proberen we alleen de naam en prijs van maximaal 10 producten op te halen.
Basis query parameters
Voor alle collecties kun je de volgende basis query parameters gebruiken:
| Parameter | Beschrijving | Voorbeeld |
|---|---|---|
limit |
Maximum aantal items om terug te geven | /api/products?limit=10 |
offset |
Aantal items om over te slaan (voor paginering) | /api/products?offset=20 |
sort |
Velden waarop gesorteerd moet worden | /api/products?sort=price |
fields |
Selecteert specifieke velden om terug te geven | /api/products?fields=name,price |
Sortering
Je kunt je resultaten sorteren met de sort parameter:
Oplopend sorteren
/api/products?sort=price
Aflopend sorteren (met voorafgaand minteken)
/api/products?sort=-price
Sorteren op meerdere velden
/api/products?sort=categoryId,-price
Dit sorteert eerst op categoryId (oplopend) en daarna op price (aflopend).
Paginering
Voor grote datasets kun je paginering gebruiken met de limit en offset parameters:
/api/products?limit=10&offset=0 // Eerste pagina
/api/products?limit=10&offset=10 // Tweede pagina
/api/products?limit=10&offset=20 // Derde pagina
Filtering op veldwaarden
Je kunt direct filteren op veldwaarden, bijvoorbeeld:
/api/products?price=19.99
Dit retourneert alle producten met een prijs van exact 19,99.
OR-filtering (meerdere waarden)
Je kunt filteren op meerdere mogelijke waarden door deze met komma's te scheiden:
/api/products?categoryId=1,2,3
Dit retourneert producten uit categorie 1 of 2 of 3.
Vergelijkingsoperatoren
Om nog extra controle te hebben over de data die geretourneerd wordt, kun je gebruik maken van vergelijkingsoperatoren:
Numeriek of datum:
| Operator | Beschrijving | Voorbeeld |
|---|---|---|
[gt] |
Groter dan | /api/products?price[gt]=20 |
[gte] |
Groter dan of gelijk aan | /api/products?price[gte]=20 |
[lt] |
Kleiner dan | /api/products?price[lt]=50 |
[lte] |
Kleiner dan of gelijk aan | /api/products?price[lte]=50 |
Tekst:
| Operator | Beschrijving | Voorbeeld |
|---|---|---|
[like] |
Overeenkomt met patroon | /api/products?name[like]=phone |
Let op: [like] is hoofdletterongevoelig en zoek ook naar delen van woorden.
Voorbeelden van vergelijkingsoperatoren
Prijsbereik filteren
Om producten te vinden met een prijs tussen 20 en 50:
/api/products?price[gte]=20&price[lte]=50
Tekstzoekopdracht
Om producten te vinden met "phone" ergens in de naam (hoofdletterongevoelig):
/api/products?name[like]=phone
Datumfilters
Om bestellingen te vinden na een bepaalde datum:
/api/orders?orderDate[gt]=2024-01-01
Complexe zoekvoorbeelden
Producten in een prijsklasse en categorie
/api/products?categoryId=2&price[gte]=10&price[lte]=50&sort=-price
Dit zoekt naar alle producten in categorie 2, met een prijs tussen 10 en 50, gesorteerd op prijs (hoogste eerst).
Recente actieve bestellingen
/api/orders?status=active&orderDate[gt]=2024-01-01&sort=-orderDate
Dit zoekt naar actieve bestellingen geplaatst na 1 januari 2024, gesorteerd op datum (nieuwste eerst).